CTL3D.TXT - version 2.01 --------- Contents of this file: What is CTL3D.PAS? Limitations imposed by CTL3D.DLL Using CTL3D in your applications A Note on Dialog Resources Using CTL3D for Windows 3.1 Only Using CTL3D for Windows 3.0 Using CTL3D With DLLs If You Have Problems What is CTL3D.PAS? ------------------ This file gives guidance on how to use the CTL3D unit with Borland Pascal 7.0 (BP7) together with Microsoft's CTL3D.DLL (vbersions 0.9 through 2.01) to equip applications for using Microsoft-style 3D dialogs and message boxes. The interface unit CTL3D.PAS takes care of all the interfacing needed with Microsoft's CTL3D DLL, for both Windows 3.0 and Windows 3.1. If your application is designed to run only under Windows 3.1, changing it to use the 3D controls is as easy as including CTL3D in the Uses clause and changing just a few lines of code. Due to the nature of Microsoft's CTL3D.DLL, some more (fairly straightforward) work is required to use 3D controls if your application is also designed to run under Windows 3.0. When you use the CTL3D interface unit in your applications, they will automatically detect the presence of CTL3D.DLL at run time, and provide 3D dialogs and message boxes if it is found. If CTL3D.DLL is not found, your application will revert to using the standard look dialogs as defined in your resource files. If your application also uses BWCC, the use of CTL3D will not interfere: it will provide the Microsoft 3D-look for any common dialogs it uses, if you desire. Limitations imposed by CTL3D.DLL --------------------------------- While the CTL3D interface unit gives your applications access to all the facilities of the CTL3D DLL, that DLL has some inherent limitations as documented by Microsoft. Briefly, these are as follows: (1) CTL3D.DLL will 'subclass' (that is, provide 3D appearance for) individual dialogs and message boxes only for VGA-resolution (640x480) displays or higher. (2) CTL3D.DLL will allow an application to 'auto-subclass' (that is, automatically provide 3D appearance for ALL that application's dialogs and message boxes) only under Windows 3.1. It cannot do this when running under Windows 3.0. Using CTL3D in your applications -------------------------------- The work you have to do to convert your applications to use CTL3D is not difficult. Just copy CTL3D.DLL to your windows/system directory and follow the instructions given below. A Note on Dialog Resources -------------------------- CTL3D works with 'standard' dialog resources created via Borland's Resource Workshop or other resource editor, but not with BWCC dialogs (those using controls supported by Borland's BWCC.DLL). It will work with these resources unchanged, but you may find you need to 'tweak' some of them a little to compensate for the slightly changed control sizes introduced by the CTL3D DLL. Using CTL3D for Windows 3.1 Only -------------------------------- If your application is designed for use only with Windows 3.1, you need only follow these simple steps: (1) Include CTL3D in the appropriate Uses clauses. CTL3D needs to be included in the Uses clause of those program units which use the TApplication object and the unit declaring your main TWindow or TMDIWindow object. Put CTL3D anywhere in the Uses clauses *AFTER* any BWCC. (2) Replace any direct reference to the following objects with the replacement shown (the easiest way is to do a global replace on your source code): Replace With ------- ---- TApplication T3dApplication TWindow T3dWindow TMDIWindow T3dMDIWindow (3) *** For users of previous versions of CTL3D.PAS only ***: In previous versions of this unit, you needed to add three parameters to your main application object's Init constructor. This is no longer necessary, and they should be removed. (4) In your application object's InitInstance method (if you haven't defined one, then you must override the one inherited from TApplication), add a call to Register3dApp as follows: Register3dApp(Name,True,,) where, is TRUE if you want the 3D dialogs to have 3D borders, or FALSE to use standard dialog borders; is TRUE if you want the Windows 3.1 common dialogs used by the application to be made 3D, or FALSE otherwise. (5) If your main window object processes the wm_SysColorChange message, ensure its method is named WMSysColorChange, and that it first calls its inherited method, thus: inherited WMSysColorChange(Msg); If your main window does not process the wm_SysColorChange message, you do *NOT* need to do this! Now recompile your application, and you should have the 3D dialogs working properly. If you experience problems, refer to the "If You Have Problems" topic at the end of this file. Using CTL3D for Windows 3.0 --------------------------- If your application is designed to run under Windows 3.0 (whether or not it can run under Windows 3.1 as well), you need to perform a little more work. The reason for this is that CTL3D.DLL does not support the 'auto-subclassing' feature available under Windows 3.1 :- this means that you have to 'sub-class' each individual dialog and common dialog. To prepare your application for using CTL3D, perform the following steps: (1) Include CTL3D in the appropriate Uses clauses. CTL3D needs to be included in the Uses clause (*AFTER* any BWCC) of those program units which declare any of the following: - the main Application object (derived from TApplication), - the main window object (derived from TWindow or TMDIWindow), - one or more dialog objects (derived from TDialog). Also, CTL3D needs to be included in the Uses clause of any program units which call any of the common dialog functions. (2) Replace any direct reference to the following objects with the replacement shown (the easiest way is to do a global replace on your source code): Replace With ------- ---- TApplication T3dApplication TWindow T3dWindow TMDIWindow T3dMDIWindow TDialog T3dDialog (3) *** For users of previous versions of CTL3D.PAS only ***: In previous versions of this unit, you needed to add three parameters to your main application object's Init constructor. This is no longer necessary, and they should be removed. (4) In your application object's InitInstance method (if you haven't defined one, then you must override the one inherited from TApplication), add a call to Register3dApp as follows: Register3dApp(Name,False,,) where, is TRUE if you want the 3D dialogs to have 3D borders, or FALSE to use standard dialog borders; is TRUE if you want to allow the Windows 3.1 common dialogs used by the application to be 3D, or FALSE otherwise. (5) If your main window object processes the wm_SysColorChange message, ensure its method is named WMSysColorChange, and that it first calls its inherited method, thus: inherited WMSysColorChange(Msg); If your main window does not process the wm_SysColorChange message, you do *NOT* need to do this! (6) If any of your dialog objects process any of the following messages, you must ensure the methods first call their inherited ancestors, thus: Message Method Identifier Insert call ------- ----------------- ----------- wm_DlgBorder WMDlgBorder inherited WMDlgBorder(Msg); wm_InitDialog WMInitDialog inherited WMInitDialog(Msg); (7) If your application calls any of the common dialog functions listed below, and you wish to use their 3D equivalents, you should replace the function names by those shown (the names are all equivalent, except for the "3d" suffix. All parameters to the common dialog functions remain unchanged: Original Name Change To ------------- --------- ChooseColor ChooseColor3D ChooseFont ChooseFont3D FindText FindText3D GetOpenFilename GetOpenFilename3D GetSaveFilename GetSaveFilename3D PrintDlg PrintDlg3D ReplaceText ReplaceText3D Now recompile your application, and you should have the 3D dialogs working properly. If you experience problems, refer to the "If You Have Problems" topic below. Using CTL3D With DLLs --------------------- If you are using CTL3D from a DLL, you can use the auto-subclassing feature under Windows 3.1 to give the 3D look to the dialogs used by the DLL's calling application (and all of the dialogs used by any DLL called by that application), as follows: (1) Include CTL3D in the appropriate Uses clauses. CTL3D needs to be included in the Uses clause of the DLL main unit. Put CTL3D anywhere in the Uses clauses *AFTER* any BWCC. (2) In your DLL's main initialisation code, add a call to Register3dDLL as follows: Register3dDLL(Name,True,,) where, is TRUE if you want the 3D dialogs to have 3D borders, or FALSE to use standard dialog borders; is TRUE if you want the Windows 3.1 common dialogs used by the application to be made 3D, or FALSE otherwise. (3) In your DLL's exit procedure, add a call to Deregister3D (this procedure takes no parameters). NB: If you do not already define your own Exit procedure for the DLL, it is recommended that you do define one and have it call Deregister3D. Refer to your BPW Language Guide for guidance on how to do this. If You Have Problems -------------------- If, when you run your modified application, none of your dialogs or message boxes appear 3D it is likely that CTL3D could not be found. You should copy CTL3D to your windows\system directory and then run your application again. If your application is runnimg under Windows 3.0 and your dialogs are not all properly shown in 3D, ensure your code does the following: (a) Objects that were declared as ancestors of TDialog are now declared as ancestors of T3dDialog. (b) Any dialog's methods that process the windows messages listed in (5) above call their inherited equivalent (NB: do not use explicit qualification such as "TDialog.WMSetText". You should use the "inherited" keyword instead). (c) Any common dialog function call now uses the replacement function listed in (6) above. -------------------------------------- Steve Hamer-Moss, CoCo Systems Ltd., UK. August 1993. EMail addresses: Compuserve: 100034,1064 CIX: shammoss and via Internet: 100034.1064@compuserve.com or shammoss@cix.compulink.co.uk